Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI String Manipulation Functions

Two types of data structures are supported for string manipulation:

- multibyte strings

- wide-character strings

Multibyte strings are encoded in native Oracle character sets. Functions that operate on multibyte strings take the string as a whole unit with the length of the string calculated in bytes. wide-character (`wchar`) string functions provide more flexibility in string manipulation. They support character-based and string-based operations with the length the string calculated in characters.

The wide-character datatype is Oracle-specific and should not be confused with the `wchar_t` datatype defined by the ANSI/ISO C standard. The Oracle wide-character datatype is always 4 bytes in all operating systems, while the size of `wchar_t` depends on the implementation and the operating system. The Oracle wide-character datatype normalizes multibyte characters so that they have a fixed width for easy processing. This guarantees no data loss for round trip conversion between the Oracle wide-character set and the native character set.

String manipulation can be classified into the following categories:

- Conversion of strings between multibyte and wide character

- Character classifications

- Case conversion

- Calculations of display length

- General string manipulation, such as comparison, concatenation, and searching

Table 21-5 summarizes the OCI string manipulation functions.

Table 21-5 OCI String Manipulation Functions

Function/Page | Purpose
--- | ---
OCIMultiByteInSizeToWideChar() | Converts part of a multibyte string into the wide-character string.
OCIMultiByteStrCaseConversion() | Converts a multibyte string into the specified case and copies the result into the destination array.
OCIMultiByteStrcat() | Appends a multibyte string to the destination string.
OCIMultiByteStrcmp() | Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods.
OCIMultiByteStrcpy() | Copies a multibyte string into the destination array. It returns the number of bytes copied.
OCIMultiByteStrlen() | Returns the number of bytes in a multibyte string.
OCIMultiByteStrncat() | Appends at most n bytes from a multibyte string to the destination string.
OCIMultiByteStrncmp() | Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. Each string is in the specified length.
OCIMultiByteStrncpy() | Copies a specified number of bytes of a multibyte string into the destination array.
OCIMultiByteStrnDisplayLength() | Returns the number of display positions occupied by the multibyte string within the range of n bytes.
OCIMultiByteToWideChar() | Converts a `NULL`-terminated multibyte string into wide-character format.
OCIWideCharInSizeToMultiByte() | Converts part of a wide-character string to the multibyte string.
OCIWideCharMultiByteLength() | Determines the number of bytes required for a wide-character in multibyte encoding.
OCIWideCharStrCaseConversion() | Converts a wide character string into the specified case and copies the result into the destination array.
OCIWideCharStrcat() | Appends a wide-character string to the destination string.
OCIWideCharStrchr() | Searches for the first occurrence of a wide character in a string. It returns a point to the wide character if the search is successful.
OCIWideCharStrcmp() | Compares two wide-character strings by binary, linguistic, or case-insensitive comparison methods.
OCIWideCharStrcpy() | Copies a wide-character string into a destination array. It returns the number of characters copied.
OCIWideCharStrlen() | Returns the number of characters in a wide-character string.
OCIWideCharStrncat() | Appends at most n characters from a wide-character string to the destination string.
OCIWideCharStrncmp() | Compares two wide-character strings by binary, linguistic, or case-insensitive methods. Each string is a specified length.
OCIWideCharStrncpy() | Copies at most n characters of a wide-character string into the destination array.
OCIWideCharStrrchr() | Searches for the last occurrence of a character in a wide-character string.
OCIWideCharToLower() | Converts a specified wide character into the corresponding lowercase character.
OCIWideCharToMultiByte() | Converts a `NULL`-terminated wide-character string into a multibyte string.
OCIWideCharToUpper() | Converts a specified wide character into the corresponding uppercase character.

## OCIMultiByteInSizeToWideChar()

Purpose

Converts part of a multibyte string into the wide-character string.

Syntax

    sword OCIMultiByteInSizeToWideChar ( dvoid         *hndl,
                                         OCIWchar      *dst,
                                         size_t        dstsz,
                                         CONST OraText *src,
                                         size_t        srcsz,
                                         size_t        *rsize );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set of the string.

dst (OUT)

  Pointer to a destination buffer for `wchar`. It can be `NULL` pointer when `dstsz` is zero.

dstsz (IN)

  Destination buffer size in number of characters. If it is zero, then this function returns the number of characters needed for the conversion.

src (IN)

  Source string to be converted.

srcsz (IN)

  Length of source string in bytes.

rsize (OUT)

  Number of characters written into destination buffer, or number of characters for converted string if `dstsz` is zero. If it is a `NULL` pointer, then nothing is returned.

Comments

This routine converts part of a multibyte string into the wide-character string. It converts as many complete characters as it can until it reaches the output buffer size limit or input buffer size limit or it reaches a `NULL` terminator in a source string. The output buffer is `NULL`-terminated if space permits. If `dstsz` is zero, then this function returns only the number of characters not including the ending `NULL` terminator needed for a converted string. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

`OCI_SUCCESS`, `OCI_INVALID_HANDLE`, or `OCI_ERROR`..

Related Functions

OCIMultiByteToWideChar()

## OCIMultiByteStrCaseConversion()

Purpose

Converts the multibyte string pointed to by `srcstr` into uppercase or lowercase as specified by the flag and copies the result into the array pointed to by `dststr`.

Syntax

    size_t OCIMultiByteStrCaseConversion ( dvoid          *hndl,
                                           OraText        *dststr,
                                           CONST OraText  *srcstr,
                                           ub4            flag );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle.

dststr (OUT)

  Pointer to destination array. The result string is `NULL`-terminated.

srcstr (IN)

  Pointer to source string.

flag (IN)

  Specify the case to which to convert:

- `OCI_NLS_UPPERCASE`: Convert to uppercase

- `OCI_NLS_LOWERCASE`: Convert to lowercase

This flag can be used with `OCI_NLS_LINGUISTIC` to specify that the linguistic setting in the locale is used for case conversion.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes for result string, not including the `NULL` terminator.

## OCIMultiByteStrcat()

Purpose

Appends a copy of the multibyte string pointed to by `srcstr` to the end of the string pointed to by `dststr`.

Syntax

    size_t OCIMultiByteStrcat ( dvoid           *hndl,
                                OraText         *dststr,
                                CONST OraText   *srcstr );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

dststr (IN/OUT)

  Pointer to the destination multibyte string for appending. The output buffer is `NULL`-terminated.

srcstr (IN)

  Pointer to the source string to append.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes in the result string, not including the `NULL` terminator.

Related Functions

OCIMultiByteStrncat()

## OCIMultiByteStrcmp()

Purpose

Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods.

Syntax

    int OCIMultiByteStrcmp ( dvoid           *hndl,
                             CONST OraText   *str1,
                             CONST OraText   *str2,
                             int             flag );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle.

str1 (IN)

  Pointer to a `NULL`-terminated string.

str2 (IN)

  Pointer to a `NULL`-terminated string.

flag (IN)

  It is used to decide the comparison method. It can take one of the following values:

- `OCI_NLS_BINARY`: Binary comparison This is the default value.

- `OCI_NLS_LINGUISTIC`: Linguistic comparison specified in the locale

This flag can be used with `OCI_NLS_CASE_INSENSITIVE` for case-insensitive comparison. For example, use `OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE` to compare strings linguistically without regard to case.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

- 0, if `str1 = str2`

- Positive, if `str1 > str2`

- Negative, if `str1 < str2`

Related Functions

OCIMultiByteStrncmp()

## OCIMultiByteStrcpy()

Purpose

Copies the multibyte string pointed to by `srcstr` into the array pointed to by `dststr`.

Syntax

    size_t OCIMultiByteStrcpy ( dvoid           *hndl,
                                OraText         *dststr,
                                CONST OraText   *srcstr );

Parameters

hndl (IN/OUT)

  Pointer to the OCI environment or user session handle.

dststr (OUT)

  Pointer to the destination buffer.The output buffer is `NULL`-terminated.

srcstr (IN)

  Pointer to the source multibyte string.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes copied, not including the `NULL` terminator.

Related Functions

OCIMultiByteStrncpy()

## OCIMultiByteStrlen()

Purpose

Returns the number of bytes in the multibyte string pointed to by `str`, not including the `NULL` terminator.

Syntax

    size_t OCIMultiByteStrlen ( dvoid          *hndl,
                                CONST OraText  *str );

Parameters

hndl (IN/OUT)

  Pointer to the OCI environment or user session handle.

str (IN)

  Pointer to the source multibyte string.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes, not including the `NULL` terminator.

Related Functions

OCIWideCharStrlen()

## OCIMultiByteStrncat()

Purpose

Appends a specified number of bytes from a multibyte string to a destination string.

Syntax

    size_t OCIMultiByteStrncat ( dvoid           *hndl,
                                 OraText         *dststr,
                                 CONST OraText   *srcstr,
                                 size_t          n );

Parameters

hndl (IN/OUT)

  Pointer to OCI environment or user session handle.

dststr (IN/OUT)

  Pointer to the destination multibyte string for appending.

srcstr (IN)

  Pointer to the source multibyte string to append.

n (IN)

  The number of bytes from `srcstr` to append.

Comments

This function is similar to `OCIMultiByteStrcat`(). At most `n` bytes from `srcstr` are appended to `dststr`. Note that the `NULL` terminator in `srcstr` stops appending and the function appends as many character as possible within `n` bytes. `dststr` is `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes in the result string, not including the `NULL` terminator

Related Functions

OCIMultiByteStrcat()

## OCIMultiByteStrncmp()

Purpose

Compares two multibyte strings by binary, linguistic, or case-insensitive comparison methods. A length is specified for each string.

Syntax

    int OCIMultiByteStrncmp ( dvoid          *hndl,
                              CONST OraText  *str1,
                              size_t         len1,
                              OraText        *str2,
                              size_t         len2,
                              int            flag );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle.

str1 (IN)

  Pointer to the first string.

len1 (IN)

  The length of the first string to compare.

str2 (IN)

  Pointer to the second string.

len2 (IN)

  The length of the second string to compare.

flag( IN)

  It is used to decide the comparison method. It can take one of the following values:

- `OCI_NLS_BINARY`: Binary comparison. This is the default value.

- `OCI_NLS_LINGUISTIC`: Linguistic comparison specified in the locale

This flag can be used with `OCI_NLS_CASE_INSENSITIVE` for case-insensitive comparison. For example, use `OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE` to compare strings linguistically without regard to case.

Comments

This function is similar to `OCIMultiByteStrcmp`(), except that at most `len1` bytes from `str1` and `len2` bytes from `str2` are compared. The `NULL` terminator is used in the comparison. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

- 0, if `str1` = `str2`

- Positive, if `str1` > `str2`

- Negative, if `str1` < `str2`

Related Functions

OCIMultiByteStrcpy()

## OCIMultiByteStrncpy()

Purpose

Copies a multibyte string into an array.

Syntax

    size_t OCIMultiByteStrncpy ( dvoid           *hndl,
                                 OraText         *dststr,
                                 CONST OraText   *srcstr,
                                 size_t           n );

Parameters

hndl (IN/OUT)

  Pointer to OCI environment or user session handle.

srcstr (OUT)

  Pointer to the destination buffer.

dststr (IN)

  Pointer to the source multibyte string.

n (IN)

  The number of bytes from `srcstr` to copy.

Comments

This function is similar to `OCIMultiByteStrcpy`(). At most `n` bytes are copied from the array pointed to by `srcstr` to the array pointed to by `dststr`. Note that the `NULL` terminator in `srcstr` stops copying and the function copies as many characters as possible within `n` bytes. The result string is `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes in the resulting string, not including the NULL terminator.

Related Functions

OCIMultiByteStrcpy()

## OCIMultiByteStrnDisplayLength()

Purpose

Returns the number of display positions occupied by the multibyte string within the range of `n` bytes.

Syntax

    size_t OCIMultiByteStrnDisplayLength ( dvoid           *hndl,
                                           CONST OraText   *str1,
                                           size_t          n );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle.

str (IN)

  Pointer to a multibyte string.

n (IN)

  The number of bytes to examine.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of display positions.

## OCIMultiByteToWideChar()

Purpose

Converts an entire `NULL`-terminated string into the wide-character string.

Syntax

    sword OCIMultiByteToWideChar ( dvoid           *hndl,
                                   OCIWchar        *dst,
                                   CONST OraText   *src,
                                   size_t          *rsize );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set of string

dst (OUT)

  Destination buffer for `wchar`.

src (IN)

  Source string to be converted.

rsize (OUT)

  Number of characters converted including `NULL` terminator. If it is a `NULL` pointer, then nothing is returned.

Comments

The `wchar` output buffer are `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

`OCI_SUCCESS`, `OCI_INVALID_HANDLE`, or `OCI_ERROR`.

Related Functions

OCIWideCharToMultiByte()

## OCIWideCharInSizeToMultiByte()

Purpose

Converts part of a wide-character string to multibyte format.

Syntax

    sword OCIWideCharInSizeToMultiByte ( dvoid            *hndl,
                                         OraText          *dst,
                                         size_t           dstsz,
                                         CONST OCIWchar   *src,
                                         size_t           srcsz,
                                         size_t           *rsize );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set of string.dst (OUT)

  Destination buffer for multibyte. It can be a `NULL` pointer if `dstsz` is zero.

dstsz (IN)

  Destination buffer size in bytes. If it is zero,then the function returns the size in bytes need for converted string.

src (IN)

  Source `wchar` string to be converted.

srcsz (IN)

  Length of source string in characters.

rsize (OUT)

  Number of bytes written into destination buffer, or number of bytes need to store the converted string if `dstsz` is zero. If it is a `NULL` pointer, then nothing is returned.

Comments

Converts part of a wide-character string into the multibyte format. It converts as many complete characters as it can until it reaches the output buffer size or the input buffer size or until it reaches a `NULL` terminator in the source string. The output buffer is `NULL`-terminated if space permits. If `dstsz` is zero, then the function returns the size in bytes not including the `NULL` terminator needed to store the converted string. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

`OCI_SUCCESS`, `OCI_INVALID_HANDLE`, or `OCI_ERROR`.

## OCIWideCharMultiByteLength()

Purpose

Determines the number of bytes required for a wide character in multibyte encoding.

Syntax

    size_t OCIWideCharMultiByteLength ( dvoid     *hndl,
                                        OCIWchar  wc );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wc (IN)

  `wchar` character.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes required for the wide character.

## OCIWideCharStrCaseConversion()

Purpose

Converts a wide-character string into a specified case and copies the result into the destination array.

Syntax

    size_t OCIMultiByteStrCaseConversion ( dvoid             *hndl,
                                           OraText           *dststr,
                                           CONST OraText     *srcstr,
                                           ub4               flag );

Parameters

ndl (IN/OUT)

  OCI environment or user session handle.

dststr (OUT)

  Pointer to destination array.

srcstr (IN)

  Pointer to source string.

flag (IN)

  Specify the case to which to convert:

- `OCI_NLS_UPPERCASE`: Convert to uppercase.

- `OCI_NLS_LOWERCASE`: Convert to lowercase.

This flag can be used with `OCI_NLS_LINGUISTIC` to specify that the linguistic setting in the locale is used for case conversion.

Comments

Converts the wide-character string pointed to by `srcstr` into uppercase or lowercase as specified by the flag and copies the result into the array pointed to by `dststr`. The result string is `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of bytes for result string, not including the `NULL` terminator.

## OCIWideCharStrcat()

Purpose

Appends the wide-character string pointed to by `wsrcstr` to the wide-character string pointed to by `wdststr`.

Syntax

    size_t OCIWideCharStrcat ( dvoid            *hndl,
                               OCIWchar         *wdststr,
                               CONST OCIWchar   *wsrcstr );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wdststr (IN/OUT)

  Pointer to the destination `wchar` string. The output buffer is `NULL`-terminated.

wsrcstr (IN)

  Pointer to the source wide-character string to append.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of characters in the result string, not including the `NULL` terminator.

Related Functions

OCIWideCharStrncat()

## OCIWideCharStrchr()

Purpose

Searches for the first occurrence of a specified character in a wide-character string.

Syntax

    OCIWchar *OCIWideCharStrchr ( dvoid            *hndl,
                                  CONST OCIWchar   *wstr,
                                  OCIWchar         wc );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wstr (IN)

  Pointer to the `wchar` string to search.

wc (IN)

  `wchar` to search for.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

A `wchar` pointer if successful, otherwise a `NULL` pointer.

Related Functions

OCIWideCharStrrchr()

## OCIWideCharStrcmp()

Purpose

Compares two wide-character strings by binary (based on `wchar` encoding value), linguistic, or case-insensitive comparison methods.

Syntax

    int OCIWideCharStrcmp ( dvoid            *hndl,
                            CONST OCIWchar   *wstr1,
                            CONST OCIWchar   *wstr2,
                            int              flag );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wstr1 (IN)

  Pointer to a `NULL`-terminated `wchar` string.

wstr2 (IN)

  Pointer to a `NULL`-terminated `wchar` string.

flag (IN)

  Used to decide the comparison method. It can take one of the following values:

- `OCI_NLS_BINARY`: Binary comparison. This is the default value.

- `OCI_NLS_LINGUISTIC`: Linguistic comparison specified in the locale definition.

This flag can be used with `OCI_NLS_CASE_INSENSITIVE` for case-insensitive comparison. For example, use `OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE` to compare strings linguistically without regard to case.

The UNICODE_BINARY sort method cannot be used with `OCIWideCharStrcmp()` to perform a linguistic comparison of supplied wide character arguments.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

- 0, if `wstr1 = wstr2`

- Positive, if `wstr1 > wstr2`

- Negative, if `wstr1 < wstr2`

Related Functions

OCIWideCharStrncmp()

## OCIWideCharStrcpy()

Purpose

Copies a wide-character string into an array.

Syntax

    size_t OCIWideCharStrcpy ( dvoid            *hndl,
                               OCIWchar         *wdststr,
                               CONST OCIWchar   *wsrcstr );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wdststr (OUT)

  Pointer to the destination `wchar` buffer.The result string is `NULL`-terminated.

wsrcstr (IN)

  Pointer to the source `wchar` string.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of characters copied not including the `NULL` terminator.

Related Functions

OCIWideCharStrncpy()

## OCIWideCharStrlen()

Purpose

Returns the number of characters in a wide-character string.

Syntax

    size_t OCIWideCharStrlen ( dvoid            *hndl,
                               CONST OCIWchar   *wstr );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wstr (IN)

  Pointer to the source `wchar` string.

Comments

Returns the number of characters in the `wchar` string pointed to by `wstr`, not including the `NULL` terminator. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of characters not including the `NULL` terminator.

## OCIWideCharStrncat()

Purpose

Appends at most `n` characters from a wide-character string to the destination.

Syntax

    size_t OCIWideCharStrncat ( dvoid            *hndl,
                                OCIWchar         *wdststr,
                                CONST OCIWchar   *wsrcstr,
                                size_t           n );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wdststr (IN/OUT)

  Pointer to the destination `wchar` string.

wsrcstr (IN)

  Pointer to the source `wchar` string.

n (IN)

  Number of characters from `wsrcstr` to append.

Comments

This function is similar to `OCIWideCharStrcat`(). At most `n` characters from `wsrcstr` are appended to `wdststr`. Note that the `NULL` terminator in `wsrcstr` stops appending. `wdststr` is `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of characters in the result string, not including the `NULL` terminator.

Related Functions

OCIWideCharStrcat()

## OCIWideCharStrncmp()

Purpose

Compares two wide-character strings by binary, linguistic, or case-sensitive methods. Each string has a specified length.

Syntax

    int OCIWideCharStrncmp ( dvoid               *hndl,
                             CONST OCIWchar      *wstr1,
                             size_t              len1,
                             CONST OCIWchar      *wstr2,
                             size_t              len2,
                             int                 flag );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wstr1 (IN)

  Pointer to the first `wchar` string.

len1 (IN)

  The length from the first string for comparison.

wstr2 (IN)

  Pointer to the second `wchar` string.

len2 (IN)

  The length from the second string for comparison.

flag (IN)

  It is used to decide the comparison method. It can take one of the following values:

- `OCI_NLS_BINARY`: For the binary comparison, this is default value.

- `OCI_NLS_LINGUISTIC`: For the linguistic comparison specified in the locale.

This flag can be used with `OCI_NLS_CASE_INSENSITIVE` for case-insensitive comparison. For example, use `OCI_NLS_LINGUISTIC`|`OCI_NLS_CASE_INSENSITIVE` to compare strings linguistically without regard to case.

Comments

This function is similar to `OCIWideCharStrcmp`(). It compares two wide-character strings by binary, linguistic, or case-insensitive comparison methods. At most `len1` bytes from `wstr1` and `len2` bytes from `wstr2` are compared. The `NULL` terminator is used in the comparison. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

The UNICODE_BINARY sort method cannot be used with `OCIWideCharStrncmp()` to perform a linguistic comparison of supplied wide character arguments.

Returns

- 0, if `wstr1 = wstr2`

- Positive, if `wstr1 > wstr2`

- Negative, if `wstr1 < wstr2`

Related Functions

OCIWideCharStrcmp()

## OCIWideCharStrncpy()

Purpose

Copies at most a `n` characters from a wide-character string into a destination.

Syntax

    size_t OCIWideCharStrncpy ( dvoid            *hndl,
                                OCIWchar         *wdststr,
                                CONST OCIWchar   *wsrcstr,
                                size_t           n );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wdststr (OUT)

  Pointer to the destination `wchar` buffer.

wsrcstr (IN)

  Pointer to the source `wchar` string.

n (IN)

  Number of characters from `wsrcstr` to copy.

Comments

This function is similar to `OCIWideCharStrcpy`(), except that at most `n` characters are copied from the array pointed to by `wsrcstr` to the array pointed to by `wdststr`. Note that the `NULL` terminator in `wdststr` stops copying and the result string is `NULL`-terminated. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

The number of characters copied not including the `NULL` terminator.

Related Functions

OCIWideCharStrcpy()

## OCIWideCharStrrchr()

Purpose

Searches for the last occurrence of a character in a wide-character string.

Syntax

    OCIWchar *OCIWideCharStrrchr ( dvoid             *hndl,
                                   CONST OCIWchar    *wstr,
                                   OCIWchar          wc );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wstr (IN)

  Pointer to the `wchar` string to search in.

wc (IN)

  `wchar` to search for.

Comments

Searches for the last occurrence of `wc` in the `wchar` string pointed to by `wstr`. If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

`wchar` pointer if successful, otherwise a `NULL` pointer.

Related Functions

OCIWideCharStrchr()

## OCIWideCharToLower()

Purpose

Converts the wide-character string specified by `wc` into the corresponding lowercase character, if it exists, in the specified locale. If no corresponding lowercase character exists, then it returns `wc` itself.

Syntax

    OCIWchar OCIWideCharToLower ( dvoid       *hndl,
                                  OCIWchar    wc );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wc (IN)

  `wchar` for lowercase conversion.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

A `wchar`.

Related Functions

OCIWideCharToUpper()

## OCIWideCharToMultiByte()

Purpose

Converts an entire `NULL`-terminated wide-character string into a multibyte string.

Syntax

    sword OCIWideCharToMultiByte ( dvoid            *hndl,
                                   OraText          *dst,
                                   CONST OCIWchar   *src,
                                   size_t           *rsize );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set of string.

dst (OUT)

  Destination buffer for multibyte string. The output buffer is `NULL`-terminated.

src (IN)

  Source `wchar` string to be converted.

srcsz (IN)

  Length of source string in characters.

rsize (OUT)

  Number of bytes written into destination buffer. If it is a `NULL` pointer, then nothing is returned.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

`OCI_SUCCESS`, `OCI_INVALID_HANDLE`, or `OCI_ERROR`.

Related Functions

OCIMultiByteToWideChar()

## OCIWideCharToUpper()

Purpose

Converts the wide-character string specified by `wc` into the corresponding uppercase character, if it exists, in the specified locale. If no corresponding uppercase character exists, then it returns `wc` itself.

Syntax

    OCIWchar OCIWideCharToUpper ( dvoid     *hndl,
                                  OCIWchar  wc );

Parameters

hndl (IN/OUT)

  OCI environment or user session handle to determine the character set.

wc (IN)

  `wchar` for uppercase conversion.

Comments

If `OCI_UTF16ID` is specified for SQL `CHAR` data in the `OCIEnvNlsCreate()` function, then this function produces an error.

Returns

A `wchar`.

Related Functions

OCIWideCharToLower()